home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / mfidx12.zip / MAKEFIDX.DOC < prev    next >
Text File  |  1990-11-20  |  14KB  |  379 lines
  1. MAKEFIDX version 1.2 - An RBBS Utility
  2. by Ken Goosens.  Nov 20, 1990
  3.  
  4. Contents
  5.     0.0  Licensing
  6.     1.0  What is MAKEFIDX?
  7.     2.0  What's New?
  8.     3.0  How to Configure RBBS-PC
  9.     4.0  How to Set Up for Files Online
  10.     5.0  How to Set Up for Files Offline
  11.     6.0  Automating Index Creation
  12.     7.0  Recompiling
  13.     8.0  An Explanation of RBBS-PC's Fast File Search
  14.  
  15.  
  16.                       0.0  Licensing
  17.  
  18. The author does not ask for any donation for use of MAKEFIDX.
  19. The rights to the code are exclusively retained by the author.
  20.  
  21. Everyone is free to use MAKEFIDX without any cost.   Everyone is
  22. free to distribute MAKEFIDX without cost, provided they charge nothing
  23. for MAKEFIDX.  You cannot distribute MAKEFIDX with any shareware or
  24. commercial product without permission of the author.   Modified
  25. versions of MAKEFIDX can be distributed only with permission of the
  26. author.  Enhancements or fixes to the code are welcome.   Anyone
  27. is free to write (and charge for) an improvement over MAKEFIDX in
  28. a language other than BASIC.  For support, the author can be reached
  29. via the RBBS conference on RBBS-Net or on his Bulletin Board at
  30. 703-978-6360.
  31.  
  32.  
  33.                 1.0  What is MAKEFIDX?
  34.  
  35. RBBS-PC, starting with version 17.3, supports a Fast File Search that
  36.  
  37. o   dramatically improves file searches on uploads and downloads
  38.  
  39. o   reduces wear and tear on hard disks
  40.  
  41. o   lets you have over 10,000 download areas
  42.  
  43. o   increases the effective limit on the number of downloadable
  44.     files to 32,767
  45.  
  46. o   introduces "do anything you want" for processing files "off line".
  47.  
  48. MAKEFIDX is a free utility for creating the index files necessary to
  49. implement and support the Fast File Search.   It should be distributed
  50. as FIDX12.ZIP and consists of the following files:
  51.  
  52. 1DISK.IMC    - Macro to invoke for files listed in DISK1.DIR
  53. ANOTHBBS.IMC - Macro informing caller on what other BBS file can be found
  54. CHAIN.IMC    - Macro objecting to files because pyramid schemes
  55. COMMERC.IMC  - Macro objecting to files because commercial
  56. DEATHSTR.DIR - List of files on DeathStar BBS (and not here)
  57. DEATHSTR.IMC - Macro to inform caller of files on DeathStar BBS
  58. DISK1.DIR    - List of files offline on floppy #1
  59. MAKEFFS.BAT  - Batch file to create a Fast File System
  60. MAKEFIDX.BAS - Source code to make Fast File System index
  61. MAKEFIDX.CFG - Configuration/driver for MAKEFIDX.EXE
  62. MAKEFIDX.DOC - Documentation for MAKEFIDX.EXE
  63. MAKEFIDX.EXE - Executable program to make FFS index
  64. MAKETABS.BAS - Source code for program to make Tabs file
  65. MAKETABS.EXE - Executable program to make Tabs file
  66. MASTER.DIR   - Sample master list of files on this BBS
  67. OFFLINE.IMC  - Macro asking if caller wants to request offline file
  68. SUPPORT.DIR  - List of files for which want special msg when downloaded
  69. SUPPORT.IMC  - Macro displaying special message for files in SUPPORT.DIR
  70. UNWANT.DIR   - List of files not wanted on this BBS
  71.  
  72.  
  73.                    2.0  What's New
  74.  
  75. Version 1.2 is "plug compatible" with 1.1.  Just replace the
  76. MAKEFIDX.EXE.  It makes the following changes:
  77.  
  78. o    increased speed
  79.  
  80. Processing of filespecs is 2 to 3 times faster.
  81.  
  82. o    better error trapping
  83.  
  84. Prior versions would abnormally terminate if a FileDir was
  85. given that did not exist.  Now just skips and continues processing.
  86.  
  87. o    better visual feedback on progress
  88.  
  89. A count is now printed on the screen of the number of entries
  90. processed in a FileSpec or FileDir .
  91.  
  92. o    increased limits
  93.  
  94. The number of filespecs that can be handled is increased from 255
  95. to 999.
  96.  
  97.  
  98. Version 1.1 made the following changes:
  99.  
  100. (a)  There is a new configuration parameter to handle non-standard
  101.      directory listings, so that MAKEFIDX can work just as well for
  102.      4DOS, or any other (see MAKEFIDX.CFG).
  103.  
  104. (b)  Lists of files can now be properly processed.
  105.  
  106. Version 1.0 would not properly handle file lists that included a
  107. drive/path in front of the file, nor lists that had only the file
  108. name on a line, nor would 1.0 properly insert macro processing into
  109. the location file.
  110.  
  111. These changes make it feasible to implement a system for processing
  112. "off line" files, which is to say that download requests for files
  113. not really present and available for downloading can still be
  114. processed.  For example, the sysop can now
  115.  
  116. o  keep infrequently downloaded files on backup media, such as
  117.    tapes for diskettes, and restore these files for downloading
  118.    the next day after they are requested.
  119.  
  120. This makes it possible for sysops to make files "available", though
  121. not immediately.   Infrequently requested files can be "archived"
  122. to backup media.   No longer is it necessary to have a gigabyte of
  123. on-line hard disks to have a gigabyte of software available.
  124. Requests for off-line files can be logged and restorals be done
  125. at the sysop's leisure.   Room can be made on the hard disk not
  126. by deleting files from the system but by moving them off-line
  127. but keeping them in the directories.
  128.  
  129. o  keep lists of files available on other BBS's.
  130.  
  131. Essentially, the BBS can become a central resource for informing
  132. callers where to go to get software.  Or, alternative, sysops can
  133. design systems to automatically call other BBS's to download
  134. requested software during the night.  You can do anything you
  135. want with requests for off-line files!
  136.  
  137.  
  138.             3.0  How to Configure RBBS-PC
  139.  
  140. The Fast File Search requires two parameters to be set up in
  141. RBBS-PC's CONFIG program:
  142.  
  143. 1.  Parmater 267 should give the file name of list of files
  144.     avaliable for downloading.   Recommended name is FIDX.DEF.
  145.     (File InDeX).
  146.  
  147. Note that the "tabs" file adds a "T" to the prefix of this
  148. file, so the prefix should be 7 characters or fewer.
  149.  
  150. 2.  Parameter 268 should give the file name of the list of
  151.     locations.  Recommended name is LIDX.DEF (Location InDeX).
  152.  
  153. You need not be concerned at all with the internal structure of
  154. these files.  MAKEFIDX will take care of all of the internals for
  155. you.
  156.  
  157. However, you probably will want to change the way the download
  158. drive/paths are configured.   RBBS-PC will always search its internal
  159. lists first, then search the file index.   To realize the potential
  160. savings in performance, you should reduce the lists of downloadable
  161. areas to at most the upload drive/path, assuming you want uploads to
  162. be available immediately for downloading.   RBBS-PC will treat
  163. everything in the file index to be downloadable, hence you basically
  164. list the downloadable files by file specification in the configuration
  165. for MAKEFIDX and not in the configuration for RBBS-PC.
  166.  
  167.  
  168.             4.0  How to Set up for Files Online
  169.  
  170. You should first put the files you want to be downloable by themselves
  171. into subdirectories.  You may want to sort them by subjects, but then
  172. you will spend much time just moving uploaded files to download areas.
  173. Most sysops just mix all the different downloadable files into different
  174. drives and subdirectories with no need to the type of file they are.
  175.  
  176. Then you basically tell MAKEFIDX what files are available for downloading
  177. by a standard DOS file specification, which usually consists of a drive and
  178. path, and wildcards.  For example,
  179.  
  180.                      C:\DWN\*.*
  181.  
  182. is all files on drive C, subsdirectory DWN.  Others are:
  183.  
  184.       D:\PICS\*.ZIP   all files on drive D, subdir PICS, with extension ZIP
  185.       C:\RBBS\BULLET* all files on drive C, subdir RBBS, with prefix BULLET
  186.  
  187.  
  188.               5.0  How to Set Up for Files Off Line
  189.  
  190. The configuration option "/FileDir=" is what allows you to add files to
  191. your lists that are off line.   The feature of RBBS-PC that allows
  192. special processing is that the location of the file (in LIDX.DEF)
  193. supports a macro to be executed in place of a file location.   The
  194. format required is
  195.  
  196. M! <macro>
  197.  
  198. For example,
  199.  
  200. M! C:\RBBS\OFFLINE.IMC
  201.  
  202. MAKEFIDX will insert macro processing by including a line at the top
  203. of the FileDir in the format:
  204.  
  205.  Directory of M! <macro>
  206.  
  207. A good way to generate an appropriate file listing is simply to do
  208. a DOS "DIR" with redirection to a file, e.g.
  209.  
  210. DIR A:*.* > DISK1
  211.  
  212. Then, with an editor, replace the line
  213.  
  214.  Directory of  A:
  215.  
  216. by
  217.  
  218.  Directory of M! DISK1.IMC
  219.  
  220. In MAKEFIDX.CFG, simply have a line
  221.  
  222. /FileDir=DISK1
  223.  
  224. MAKEFIDX will put into LIDX.DEF whatever occurs after "Directory of"
  225. and will take it to be the location of all the file names that follow
  226. that line.
  227.  
  228. The macro file DISK1.IMC might then contain
  229.  
  230. 1
  231. {:= 2 #1
  232. {M! OFFLINE.IMC
  233.  
  234. The second line basically sets an identifier for the appropriate back
  235. up source to be used.
  236.  
  237. The macro in turn invoked, OFFLINE.IMC, might contain
  238.  
  239. 1
  240. {*B
  241.  
  242.  
  243.      The file {FI is {C1not available{C0 immediately, but is
  244.      stored {C1off line{C0 and can be {C2restored{C0 for you by
  245.      the SysOp within 24 hours.
  246.  
  247. {END
  248. {TK
  249. {01Request that the sysop restore the file (Y,N)
  250. {ON 1
  251. {==Y
  252. {>> C:\RBBS\PLZRESTR.DAT
  253. {FI from [2] for {FN {LN, {DT {TM
  254. {END
  255. {*1 Please check back tomorrow for {FI
  256. {END ON
  257.  
  258. This simply logs to file PLZRESTR.DAT requests to store the file.
  259. Note that the log gives with file name, disk id to restore from,
  260. and who make the request when, using RBBS-PC's work variables and
  261. SmartText variables.
  262.  
  263.  
  264.              6.0  Automating Index Creation
  265.  
  266. The process of maintaining a list of files for the RBBS-PC Fast File
  267. Search can be automated.  MAKEFFS.BAT is an example of a batch file
  268. automating this process.   The steps are:
  269.  
  270. 1.   Create a list of files not online but to be added to the Fast
  271.      File Search.   The substeps in this process are:
  272.  
  273.      a.  keep a list of all of the on-line files on your system, e.g.
  274.          MASTER.DIR.   Put this is the master list in CMPBBS.CFG.
  275.  
  276.      b.  keep lists of all additional new files to be added to the
  277.          fast file system.  Set them to "AddList"s in CMPBBS.CFG.
  278.          Be sure to put in a header specifying a macro to execute.
  279.  
  280.      c.  Run CMPBBS to create a list of new files to add.   Put this
  281.          new file list in as a "FileDir" in MAKEFIDX.CFG.
  282.  
  283. 2.   Set up MAKEFIDX.CFG to refer by filespec to include all
  284.      downloadable files (except those in the upload directory).
  285.  
  286. 3.   Run MAKEFIDX to create both a combined list of all files on
  287.      and offline, and well as a location file.
  288.  
  289. 4.   Sort the combined list of files (FIDX.DEF) on the file name.
  290.  
  291. Note:  step 4 is set up in the batch file to use the shareware
  292. program QSORT, which is not provided.   Any good sorting program
  293. can be used instead.
  294.  
  295. 5.   Run MAKETABS to produced an index on the sorted file list to
  296.      further speed up searches.
  297.  
  298.  
  299.                       7.0  Recompiling
  300.  
  301. MAKEFIDX and MAKETABS are written in Basic for MicroSoft's
  302. QuickBasic, and will compile in 4.5 up.   Assember routines are
  303. used from Tom Handlin's shareware Advanced Basic Library.
  304.  
  305. The commands to recompile are:
  306.  
  307. BC MAKEFIDX /O/X;
  308. LINK MAKEFIDX,,,ADVBAS;
  309.  
  310. BC MAKETABS /O/X;
  311. LINK MAKETABS;
  312.  
  313.  
  314.        8.0  An Explanation of RBBS-PC's Fast File Search
  315.  
  316. For directories DOS uses chained "buckets" in multiple locations, 
  317. searched sequentially.   This results in very slow performance when
  318. the number of files to search gets into the thousands.   RBBS now
  319. supports a fast file search than more than compensates for the
  320. inefficent operation in DOS.
  321.  
  322. The basis for the fast file search is a file, configuration
  323. parameter 267, which is a sorted list of file names available for
  324. downloading.    The default name is FIDX.DEF.
  325.  
  326. The format of this file is:
  327.  
  328. columns 1-12:  file name
  329. columns 13-16: location index (1, 2, 3, ...)
  330. columns 17-18: carriage return line feed.
  331.  
  332. All data is stored as character data and the file is editable.   The file
  333. names must be stored with no internal spaces and a period separating the
  334. prefix from the extension.   The list of file names MUST BE SORTED BY
  335. FILE NAME in order for the fast file search to work.
  336.  
  337. The location index is the record number (line number) of the locator file,
  338. whose default name is LIDX.DEF, and has the following layout:
  339.  
  340. columns 1-63:  location of file
  341. column  64:    any character.  MAKEFIDX puts in a period.
  342. columns 65-66: carriage return line feed.
  343.  
  344. This file is all character data and is editable.   Essentially, the location
  345. index points to a record in the location file.   E.g. if FIDX.DEF has
  346.  
  347. RBBS-BAS.ZIP   2
  348. HARPIE.ARC     3
  349.  
  350. and LIDX.DEF has
  351.  
  352. C:\DOWN1\
  353. C:\DOWN2\
  354. C:\UP\
  355.  
  356. Then RBBS-BAS.ZIP is located in directory C:\DOWN2 (2nd record) and 
  357. HARPIE.ARC is located in C:\UP (3rd record).
  358.  
  359. The location field should be a drive/path terminating with a "\" if
  360. any path is given, and file must be filled with blanks through column
  361. 63 if the path is shorter.  You must put some character in column 64.
  362. Many editors delete trailing blanks, so you should probably put in
  363. a non-blank.  A period is a suitable choice.
  364.  
  365. RBBS will use a binary search on the first 12 characters in FIDX.DEF.
  366. This binary search can be significantly speeded by provided "tabs" for
  367. this file, indicating the record at which the first file is that begins
  368. with the symbols "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ".   This is like
  369. the "tabs" you see on dictionaries, so you can directly turn to the B's,
  370. for example.   A tab file has the same prefix as the file name file,
  371. except that it adds a "T".  For "FIDX.DEF", the tab file would be
  372. "FIDXT.DEF".   RBBS will automatically detect and use a tab file if
  373. available.   The tab has 72 characters in it.   Each 2 bytes represents
  374. a binary integer whose value is the record number in FIDX.DEF where the
  375. first file occurs that begins with the respective symbols above.  Thus
  376. bytes 3-4 show where files begin with "1" and bytes 69-70 where files
  377. begin with "Y".
  378.  
  379.